home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / installed_progs / dev / pattern.library+pgrep / pattern.doc < prev    next >
Text File  |  1994-07-04  |  35KB  |  1,074 lines
  1. TABLE OF CONTENTS
  2.  
  3. pattern.library/--background--
  4. pattern.library/--disclaimer--
  5. pattern.library/--history--
  6. pattern.library/--rexxhost--
  7. pattern.library/--thanx--
  8. pattern.library/AllocPattern
  9. pattern.library/AllocPatternNoCase
  10. pattern.library/Char2Lower
  11. pattern.library/Char2Upper
  12. pattern.library/ESCPattern
  13. pattern.library/GetAllocCounter
  14. pattern.library/FreePattern
  15. pattern.library/IsPattern
  16. pattern.library/MatchThePattern
  17. pattern.library/PatternError2DOS
  18. pattern.library/PatternErrorString
  19. pattern.library/SimpleMatch
  20. pattern.library/SimpleMatchNoCase
  21. pattern.library/Str2Lower
  22. pattern.library/Str2Upper
  23. pattern.library/XMatchPattern
  24. pattern.library/XMatchPatternNoCase
  25. pattern.library/XParsePattern
  26. pattern.library/XParsePatternNoCase
  27.  
  28.  
  29. pattern.library/--background--                   pattern.library/--background--
  30.  
  31.    PURPOSE
  32.     This is a library that helps you in
  33.       - pattern matching
  34.       - pattern matching with AmigaDOS 2.0 compatible calls (very slow)
  35.       - converting strings and characters to uppercase and lowercase
  36.         including international characters.
  37.     This library knows the following special characters:
  38.       - #   The following expression or character may be repeated
  39.         any number of times, including 0.
  40.       - ?   Matches any single character.
  41.       - |   Matches any expression separated by '|'. In AmigaDOS 2.0
  42.         the syntax is "(abc|xyz)"; the pattern.library's syntax is
  43.         either "(abc|xyz)" or "abc|xyz".
  44.       - ()  With these parentheses it's possible to modify the
  45.         evaluation sequence while parsing the string. The
  46.         parentheses may be nested.
  47.       - %   A joker for an empty expression like "".
  48.       - '   The following character will not be taken as a special
  49.         character, e.g. "'?" is equivalent to the character "?".
  50.     These were AmigaDOS 1.3 pattern. Now have a look at the following:
  51.       - *   Matches any number of characters. Synonymous to "#?" in
  52.         AmigaDOS, but shorter.
  53.       - ~   Negates the following expression and matches all strings
  54.         that do not match exactly to the expression. E.g. ~(abc)
  55.         matches to every string that is not exactly "abc",
  56.         e.g. "_abc".
  57.         No equivalence in AmigaDOS 1.3.
  58.       - []  The characters or expressions inside these brackets - e.g.
  59.         [a#bc(de)] will be interpreted as (a|#b|c|de). This is much
  60.         shorter then the AmigaDOS 1.3 pattern.  There may also be a
  61.         character-range within the brackets, e.g. [c-h], which
  62.         allows any characters from "c" to "h".
  63.         If you want the charater "-" to be in the class, put it
  64.         directely after "[" or in front of "]".
  65.         [~chars] matches any of the characters that are not in
  66.         the class.
  67.         NOTE: AmigaDOS 2.0 will match "[#?]" to the characters "#"
  68.               and "?". pattern.library will match with any string
  69.               since "#?" is an expression. If you want to force the
  70.               same behaviour as AmigaDOS 2.0, you should type
  71.               "['#'?]".
  72.  
  73.     There are matching functions for case-sensitive and case-insensitive
  74.     pattern as well. Function-names that contain "NoCase" are
  75.     case-insensitive.
  76.  
  77.    EXAMPLES
  78.     *1#0                      Matches e.g. Amiga1000, Amiga1
  79.     ~(Amiga500)               Matches e.g. Amiga1000, _Amiga500
  80.     ~(*Amiga500)              Matches e.g  Amiga1000, not _Amiga500
  81.     #[~0-9]1#0                Matches e.g. Amiga1000
  82.     Amig?#[~a-zA-Z125-9]      Matches e.g. Amiga0003
  83.     Amiga'*000                Matches only Amiga*000
  84.     #a(#m(#i(#g(#a*))))       Matches e.g. Ammiiigaaaagaagaack
  85.     (Amiga|Amig[io])(1000|%)  Matches e.g. Amiga, Amigo1000
  86.     #A#m#i#g#a|A*a            Matches e.g. Angela
  87.  
  88.    FEATURES
  89.     1) Matching:
  90.        Matches better than AmigaDOS 2.04. For example, AmigaDOS 2.04
  91.        thinks that "#(#a#b)" does not match with "aba" and that "#(%|a)"
  92.        does not match with "aa". pattern.library is able to perform such
  93.        matching operations.
  94.        AmigaDOS 2.0 needs parentheses around "|", e.g. (a|bc), which is
  95.        not necessary in pattern.library, e.g. a|bc. Of course,
  96.        parentheses are allowed!
  97.     2) Speed:
  98.        pattern.library tries to optimize things for speed. e.g
  99.        "#(#<exp1>#<exp2>..)" will be optimized to "#(<exp1>|<exp2>..)"
  100.        which means exactly the same but will match faster.
  101.        A special built-in pre-match function will pre-check pattern and
  102.        string if there's any possibility that the string matches with
  103.        the pattern. If not, the result will be returned immediatly.
  104.        Pre-check also has a little built-in function that will - in this
  105.        library-version - match the following things faster than the
  106.        standard matching routine:
  107.        "*", "%", "<str>", "[*]<str>[*]...", "<str1>|<str2>...",
  108.        "[?]<str>[?]...".
  109.        <str> must not contain another pattern. These are patterns that
  110.        are used very often.
  111.        If a "~" is the first charater of the pattern and if it's
  112.        followed by parentheses that include one of the quick-matching
  113.        things, matching will also be quick - e.g. ~(*.info)
  114.        Perhaps there will be more optimized pattern included in future
  115.        versions.
  116.        Please note that I can't reach the matching speed of AmigaDOS 2.04
  117.        in every case since AmigaDOS 2.04 does not check all possible
  118.        alternatives.
  119.        Try to stop the time, ARP or AmigaDOS 2.0 needs to match the
  120.        pattern "a#?#?#?#?#?#?#?b" with "aaaaaaaaaaaaaaaaaaaaaaaaa"
  121.     3) Languages:
  122.        This library supports a number of error-strings in different
  123.        languages to return an error-message. If you want to be able to
  124.        use all supported languages, please copy the file
  125.        "Config-Pattern" into your "S:"-directory. Feel free to strip
  126.        languages you don't need.
  127.  
  128.    IMPORTANT
  129.     Only processes may open and close this library, no tasks. Some
  130.     functions must only be called by a process since the function might
  131.     use a dos.library-call.
  132.  
  133.    BUGS
  134.     - Functions *may* need a lot of stack (in most cases they do not
  135.       need much stack), but stack checking is not yet implemented.
  136.  
  137.    TODO
  138.     - SearchPattern(): Searches a pattern in a buffer in O(n^2*m)
  139.     - MatchFirst(), MatchNext(), MatchEnd()
  140.     - More speed while matching: O(n*m)
  141.     - Patchtool to patch ARP and Amiga OS 2.0 pattern matching (who
  142.       wants to write a patchprogram to patch AmigaDOS 1.3
  143.       pattern matching?  :-)
  144.  
  145.  
  146. pattern.library/--disclaimer--                   pattern.library/--disclaimer--
  147.  
  148.    COPYRIGHT
  149.     pattern.library, its documentation and all its programmer stuff
  150.     and applications are copyrighted (C) 1992 by Angela Schmidt
  151.     You must not do anything with this stuff except the things listed
  152.     below.
  153.  
  154.    USER
  155.    DISTRIBUTOR
  156.     This is the disclaimer for all users who want to use any part of
  157.     this package.
  158.  
  159.     1) Use
  160.        You're allowed to use these things, but there's no guarantee
  161.        that everything works correctly. If you use these programs, you
  162.        do so at your own risk! If you find unknown bugs, please report
  163.        them.
  164.  
  165.     2) Distribution
  166.        Feel free to give these things away to your friends if you make
  167.        NO PROFIT with it, but remember to spread it in its entirety.
  168.        The following files HAVE TO BE included:
  169.  
  170.         pattern.library ... Copy this to LIBS:
  171.         pattern.doc ....... User information and programmer-docs
  172.         pattern.h ......... Programmer include file
  173.         pattern_lib.fd .... Programmer fd-file
  174.         Config-Pattern .... This contains the errormessages and
  175.                     should go to S:
  176.         README ............ General information
  177.         FILES ............. Info about the files, that are available
  178.  
  179.        The following files MAY be included:
  180.  
  181.          1) pgrep ............. A small grep utility
  182.         pgrep.doc.......... Documentation for pgrep
  183.          2) PatternTest ....... Test-program with intuition-interface
  184.                     Also tests arp.library and dos.library
  185.                     With a German user-interface
  186.         PatternTest.info... Icon for PatternTest to start from WB
  187.          3) LibMain(NoCase).... Test-programs to start in CLI
  188.         LibMain.c ......... C-Source to LibMain(NoCase)
  189.         LibMain.Doc ....... short documentation
  190.         test/*.tst ........ Test-files for LibMain
  191.                     e.g. "1> LibMain <test/pt1.tst"
  192.          4) pattern.mod ....... Programmer Amiga Oberon Library Module
  193.  
  194.        · NOTHING must be changed/patched in these files!
  195.        · All files have to be in the same directory. There must not be
  196.          any foreign file in that directory.
  197.        · Don't sell any part of this package for profit! You may only
  198.          demand the price of an empty disk and a SMALL copy fee.
  199.          This excludes also bundling the pattern.library as "freebie"
  200.          with any kind of product. 
  201.        · These things may be only crunched or coded using freely
  202.          distributable programs so that everyone can decrunch or decode
  203.          it without having to purchase the necessary programs.
  204.        · Further ideas to make profit with this are not allowed as well.
  205.        · Only non-profit PD-disk series may include pattern.library!
  206.        · And here explicitely:
  207.          This may be only included on any CD's if you get my permission
  208.          to do so. You probably will get it, if nobody will make profit
  209.          with the CD. You even MUST NOT include it on Fred Fish CD's
  210.          if anybody makes profit with it!!!
  211.          This package may be included on the Meeting Pearls CD!
  212.  
  213.        There's one exception to include this package on other disks:
  214.        If there's an application that NEEDS the pattern.library, you
  215.        may include this package on disks that are not listed above or
  216.        that are sold. But note, that in this case you MUST NOT
  217.        advertise for any part of this package, since nobody should
  218.        get your disk because of the pattern.library and the other
  219.        stuff! For more information about using these routines see
  220.        below.
  221.  
  222.        I have stated the above conditions, because I learnt the hard way
  223.        that there are too many people who make their money with freely
  224.        distributable software on disks and CD's and I hate th(is|em).
  225.  
  226.     3) For further use you have to ask me.
  227.  
  228.    PROGRAMMERS
  229.     This is the disclaimer for all programmers who want to call these
  230.     routines or routines that use these routines (and so on...).
  231.     1) Programs that will not be spread
  232.        Feel free to implement these routines in your own applications
  233.        if you won't spread them.
  234.     2) Programs that will be spread
  235.        a) Public Domain, Freeware
  236.           If you use these routines in applications that will be
  237.           spread, and if there's no turnover expected, feel free to
  238.           use my routines. If you like, you could send me a copy of
  239.           your program as a little acknowledgment for my work with the
  240.           pattern.library.
  241.        b) Other Software
  242.           If your turnover made with the package containing the
  243.           pattern.library is less than 10,000 US-Dollar, send me your
  244.           released program with its documentation free of charge. If
  245.           there are any updates that use the pattern.library, you need
  246.           not send more than one update per year.
  247.           If you expect a turnover of 10,000 US-Dollars or more (or
  248.           anything that has the equivalent value), or if you
  249.           unexpectedly reach this limit, you MUST contact me for further
  250.           spreading conditions. You MUST NOT use these routines if you
  251.           don't contact me.  BTW im most cases there won't be a large
  252.           change for you when you reach this limit.
  253.        For spreading conditions together with your applications see
  254.        above.
  255.  
  256.    ADDRESS
  257.     My addresses are:
  258.  
  259.     +----------------+------------------------------------------------+
  260.     | home address   | college (and place of my Amiga 1000)           |
  261.     +----------------+------------------------------------------------+
  262.     | Angela Schmidt | Angela Schmidt                                 |
  263.     | Finkenweg 26   | Klosterweg 28/I501                             |
  264.     | 89233 Neu-Ulm  | 76131 Karlsruhe                                |
  265.     | Germany        | Germany                                        |
  266.     | +49 731/712316 | +49 721/695307 (9am - 10pm MET)                |
  267.     | (10am-9pm MET) | Angela@rz.uni-karlsruhe.de                     |
  268.     |                | Nessy@IRC                                      |
  269.     +----------------+------------------------------------------------+
  270.  
  271.  
  272. pattern.library/--history--                         pattern.library/--history--
  273.  
  274.    VERSION_5
  275.     The following functions are available in version 5 of the
  276.     pattern.library:
  277.        AllocPattern
  278.        AllocPatternNoCase
  279.        Char2Lower
  280.        Char2Upper
  281.        ESCPattern
  282.        FreePattern
  283.        GetAllocCounter
  284.        IsPattern
  285.        MatchThePattern
  286.        PatternError2DOS
  287.        PatternErrorString
  288.        SimpleMatch
  289.        SimpleMatchNoCase
  290.        Str2Lower
  291.        Str2Upper
  292.        Surprise
  293.        XMatchPattern
  294.        XMatchPatternNoCase
  295.        XParsePattern
  296.        XParsePatternNoCase
  297.    VERSION_5.1
  298.        Two bugfixes: · no more enforcerhits while matching "a|b"
  299.                      · "???..." now is no longer treated as "(???...)".
  300.  
  301.    VERSION_6
  302.     Not yet available... :-(
  303.  
  304.    NOTE!!!
  305.     Since I've spread some alpha-versions of the pattern.library with
  306.     other library-vectors than in this fd-file, remember to open the
  307.     pattern.library with the version number 5L (or higher in future
  308.     versions):
  309.        if (PatternBase=(struct Library *) OpenLibrary (PATLIB_NAME, PATLIB_MIN_VERSION)) {
  310.           /* Lib-Calls */
  311.           CloseLibrary (PatternBase);
  312.        }
  313.     Where PATLIB_NAME is #defined to "pattern.library" and
  314.     PATLIB_MIN_VERSION is #defined to 5L. (See "pattern.h")
  315.  
  316.  
  317. pattern.library/--rexxhost--                       pattern.library/--rexxhost--
  318.  
  319.    HOST INTERFACE
  320.     pattern.library provides an ARexx function host interface that
  321.     enables ARexx programs to take advantage of the wonderful
  322.     pattern matching of this library.
  323.  
  324.     The function host library vector is located at offset -30 from the
  325.     library. This is the value you provide to ARexx in the AddLib()
  326.     function call.
  327.  
  328.    FUNCTION
  329.     Str2Upper(STRING/A)
  330.     Str2Lower(STRING/A)
  331.     PatternMatch(PATTERN/A,STRLIST/A,SEPCHAR,ERRORSTR,LANGUAGE)
  332.     PatternMatchNoCase(PATTERN/A,STRLIST/A,SEPCHAR,ERRORSTR,LANGUAGE)
  333.     PatternErrorString(ERRNUM/N/A,LANGUAGE)
  334.  
  335.     NOTE: A string must not contain a '\0'-Byte, otherwise it will
  336.           be truncated at that position.
  337.  
  338.        Str2Upper
  339.         Converts a string to uppercase, including umlauts
  340.  
  341.        Str2Lower
  342.         Converts a string to lowercase, including umlauts
  343.  
  344.        PatternMatch
  345.         Matches a pattern with the strings in the list. The strings
  346.         are separated by the character specified in the 3rd
  347.         parameter - if there's any. Otherwise space (0x20) will be
  348.         used as a default.
  349.         The function returns a list of all strings that matched.
  350.         If there occurs an error, the return string will begin with
  351.         <ERRORSTR> followed by a number and the errormessage.
  352.         If <ERRORSTR> is not specified, it will begin with 0x00.
  353.         If <LANGUAGE> is not specified, the default language will be
  354.         used to create the errormessage.
  355.         NOTE: You can't match strings, that contain a 0x00-Byte,
  356.               but you're allowed to use 0x00 as a
  357.               separating-character.
  358.        PatternMatchNoCase
  359.         Same as above but case-insensitive.
  360.  
  361.        PatternErrorString
  362.         Returns the errormessage using the specified language. If
  363.         there's no language specified, the default language will be
  364.         used.
  365.  
  366.    EXAMPLE
  367.     /* patternexample.rexx */
  368.  
  369.     /* Make sure pattern.library V5 is loaded as a function host */
  370.     IF ~SHOW('L','pattern.library') THEN DO
  371.        CALL ADDLIB('pattern.library',0,-30,5)
  372.     END
  373.  
  374.     say Str2Upper('FooBar')
  375.     say Str2Upper('Test: äöüÄÖÜéèêÉÈÊ')
  376.     say Str2Lower('FooBar')
  377.     say Str2Lower('Test: äöüÄÖÜéèêÉÈÊ')
  378.  
  379.     say PatternMatch('???','foo foobar bar blubber')
  380.     say PatternMatch('???','foo_foobar_bar_blubber','_')
  381.  
  382.     say PatternMatch('#(a#(m#(i#(g#a))))','Aaaamiiiiggga aaamiiigaaa ami angela')
  383.     say PatternMatchNoCase('#(a#(m#(i#(g#a))))','Aaaamiiiiggga aaamiiigaaa ami angela')
  384.  
  385.     say PatternMatch('#(ga)#[bnae]','ga-blubb-gaga-hicks-banane-boing-gagabanane','-')
  386.  
  387.     IF ~SHOW('L','rexxsupport.library') THEN DO
  388.        CALL ADDLIB('rexxsupport.library',0,-30,0)
  389.     END
  390.  
  391.     say PatternMatchNoCase('~(*.info)',ShowDir('SYS:'))
  392.     say PatternMatchNoCase('*[a-e][n-t]?[~a-clmnx-z]*',ShowDir('C:'))
  393.     say PatternMatchNoCase('*info*|~(*[aiu]*)|??',ShowDir('C:'))
  394.  
  395.     say 'Now you will see an english error message:'
  396.     say PatternMatch('[foo','dummy',,'Error: ','english')
  397.  
  398.  
  399. pattern.library/--thanx--                             pattern.library/--thanx--
  400.  
  401.    THANX
  402.     Thanx to all my betatesters for bugreports!
  403.     Expecially to:
  404.     · Bernhard for writing the test-program PatternTest with its
  405.       intuition-interface. For speed-up ideas, memory-managing
  406.       routines, stdio routines in pgrep and for the help in building
  407.       a shared library.
  408.     · Matt Dillon for his NICE DICE :)
  409.     · Mr.Scary for translating my Germ-English into something like real
  410.       English...
  411.  
  412.  
  413. pattern.library/AllocPattern                       pattern.library/AllocPattern
  414.  
  415.    NAME
  416.     AllocPattern -- Compiles a pattern for use with MatchThePattern()
  417.  
  418.    SYNOPSIS
  419.     PatternHandle = AllocPattern (pattern, flags)
  420.     D0                            A0       D0
  421.  
  422.     LONG AllocPattern (STRPTR, ULONG)
  423.  
  424.    FUNCTION
  425.     This function compiles a pattern into a special internal format
  426.     which is used by MatchThePattern() to test if special strings match
  427.     with the pattern or not. This function is case-sensitive.
  428.  
  429.    INPUTS
  430.     pattern - pointer to a null-terminated string which contains the
  431.           pattern.
  432.     flags - for future use only. MUST be set to 0L.
  433.  
  434.    RESULT
  435.     PatternHandle - A positive value if everything went right.
  436.             A negative value signals a fatal error. Use
  437.             the negative value to identify the error.
  438.  
  439.    BUGS
  440.     No known bugs
  441.  
  442.    SEE ALSO
  443.     FreePattern(), MatchThePattern(), PatternErrorString(),
  444.     PatternError2DOS()
  445.  
  446.  
  447. pattern.library/AllocPatternNoCase           pattern.library/AllocPatternNoCase
  448.  
  449.    NAME
  450.     AllocPatternNoCase -- Compiles a pattern for use with
  451.                   MatchThePattern()
  452.  
  453.    SYNOPSIS
  454.     PatternHandle = AllocPatternNoCase (pattern, flags)
  455.     D0                                  A0       D0
  456.  
  457.     LONG AllocPatternNoCase (STRPTR, ULONG)
  458.  
  459.    FUNCTION
  460.     This function compiles a pattern into a special internal format
  461.     which is used by MatchThePattern() to test if special strings match
  462.     with the pattern or not.  This function is case-insensitive.
  463.  
  464.    INPUTS
  465.     pattern - pointer to a null-terminated string which contains the
  466.           pattern.
  467.     flags - for future use only. MUST be set to 0L.
  468.  
  469.    RESULT
  470.     PatternHandle - A positive value if everything went right.
  471.             A negative value signals a fatal error. Use
  472.             the negative value to identify the error.
  473.  
  474.    BUGS
  475.     No known bugs
  476.  
  477.    SEE ALSO
  478.     FreePattern(), MatchThePattern(), PatternErrorString(),
  479.     PatternError2DOS()
  480.  
  481.  
  482. pattern.library/Char2Lower                           pattern.library/Char2Lower
  483.  
  484.    NAME
  485.     Char2Lower -- Converts a char to lowercase, including umlauts
  486.  
  487.    SYNOPSIS
  488.     lowerchar = Char2Lower (anychar)
  489.     D0 - 0:8                D0 - 0:8
  490.  
  491.     UBYTE Char2Lower (UBYTE)
  492.  
  493.    FUNCTION
  494.     This function converts a given character - including umlauts - to
  495.     lowercase. If "anychar" is a non-alphabetical character, the
  496.     character is returned, unchanged.
  497.  
  498.    INPUTS
  499.     anychar - the character that is to be converted.
  500.  
  501.    RESULT
  502.     lowerchar - the converted character.
  503.  
  504.    BUGS
  505.     No known bugs
  506.  
  507.    SEE ALSO
  508.     Char2Upper(), Str2Lower(), Str2Upper()
  509.  
  510.  
  511. pattern.library/Char2Upper                           pattern.library/Char2Upper
  512.  
  513.    NAME
  514.     Char2Upper -- Converts a char to uppercase, including umlauts
  515.  
  516.    SYNOPSIS
  517.     upperchar = Char2Upper (anychar)
  518.     D0 - 0:8                D0 - 0:8
  519.  
  520.     UBYTE Char2Upper (UBYTE)
  521.  
  522.    FUNCTION
  523.     This function converts a given character - including umlauts - to
  524.     uppercase. If "anychar" is a non-alphabetical character, the
  525.     character is returned, unchanged.
  526.  
  527.    INPUTS
  528.     anychar - the character that is to be converted.
  529.  
  530.    RESULT
  531.     upperchar - the converted character.
  532.  
  533.    BUGS
  534.     No known bugs
  535.  
  536.    SEE ALSO
  537.     Char2Lower(), Str2Lower(), Str2Upper()
  538.  
  539.  
  540. pattern.library/ESCPattern                           pattern.library/ESCPattern
  541.  
  542.    NAME
  543.     ESCPattern -- Converts a string into a pattern
  544.  
  545.    SYNOPSIS
  546.     result = ESCPattern (source, dest, flags)
  547.     D0                   A0      A1    D0
  548.  
  549.     STRPTR ESCPattern (STRPTR, STRPTR, ULONG)
  550.  
  551.    FUNCTION
  552.     This function converts a given string into a pattern.  So every
  553.     pattern character will be escaped.  E.g.  the string "50% or more?"
  554.     will become "50'% or more'?".
  555.  
  556.    INPUTS
  557.     source - A pointer to the string to be converted.
  558.     dest   - A pointer to a buffer that is at least twice as large as
  559.          source plus one byte.
  560.     flags  - Must be zero for now.
  561.  
  562.    RESULT
  563.     result - A pointer to the converted string.
  564.  
  565.    BUGS
  566.     No known bugs
  567.  
  568.    SEE ALSO
  569.     IsPattern()
  570.  
  571.  
  572. pattern.library/FreePattern                         pattern.library/FreePattern
  573.  
  574.    NAME
  575.     FreePattern -- Frees the resources allocated by MatchThePattern()
  576.  
  577.    SYNOPSIS
  578.     FreePattern (PatternHandle)
  579.              D0
  580.  
  581.     void FreePattern (LONG)
  582.  
  583.    FUNCTION
  584.     This function frees all resources allocated by AllocPattern()
  585.     or AllocPatternNoCase(). You have to call this when you don't
  586.     need the allocated patternhandle any more.
  587.  
  588.    INPUTS
  589.     PatternHandle - The longword you received by AllocPattern()
  590.             or AllocPatternNoCase().
  591.  
  592.    RESULT
  593.     Exec's memory-manager feels happy
  594.  
  595.    BUGS
  596.     No known bugs
  597.  
  598.    SEE ALSO
  599.     AllocPattern(), AllocPatternNoCase()
  600.  
  601.  
  602. pattern.library/GetAllocCounter                 pattern.library/GetAllocCounter
  603.  
  604.    NAME
  605.     GetAllocCounter -- Returns the number of allocated patterns.
  606.  
  607.    SYNOPSIS
  608.     counter = GetAllocCounter()
  609.     D0
  610.  
  611.     LONG GetAllocCounter()
  612.  
  613.    FUNCTION
  614.     This function returns the number of allocated and non-freed patterns.
  615.     This is useful while patching pattern matching functions using
  616.     SetFunction(). There's a problem while patching matching-functions.
  617.     Since every allocated pattern has its own format returned by
  618.     pattern.library/AllocPattern, arp.library/PreParse,
  619.     dos.library/ParsePattern... you have to make sure that there's
  620.     no allocated pattern while patching any matching- or free-function.
  621.     Otherwise a library may get a pattern compiled by an other
  622.     library. This might cause mysterious things...
  623.     You may only patch these allocation-, matching- and free-routines
  624.     if GetAllocCounter() returns 0.
  625.     NOTE: Even this is not safe if you use GetAllocCounter(). Remember
  626.     that any program could be in the library's interface-stuff or at the
  627.     very beginning of the matching routine. But it's much better than
  628.     patching without checking anything. There's NO way to make patching
  629.     these routines totally safe. But let's try to make it as safe as
  630.     possible!
  631.     This function was NOT written to patch any library vectors of the
  632.     pattern.library :-(. It was only written to make unpatching
  633.     arp.library, dos.library, ... safer.
  634.  
  635.    INPUTS
  636.     No inputs
  637.  
  638.    RESULT
  639.     counter - the number of allocated patterns.
  640.  
  641.    BUGS
  642.     No known bugs
  643.  
  644.    SEE ALSO
  645.     -
  646.  
  647.  
  648. pattern.library/IsPattern                             pattern.library/IsPattern
  649.  
  650.    NAME
  651.     IsPattern -- Checks if a given string is a pattern.
  652.  
  653.    SYNOPSIS
  654.     result = IsPattern (pattern, topattern, flags)
  655.     D0                  A0       A1         D0
  656.  
  657.     LONG IsPattern (STRPTR, STRPTR, ULONG)
  658.  
  659.    FUNCTION
  660.     This function tests if a given string contains pattern-tokens and
  661.     copies the string without quotes into topattern. For example "'?'*"
  662.     becomes to "?*". This pattern may be compared with a string faster
  663.     using strcmp().
  664.  
  665.    INPUTS
  666.     pattern   - pointer to a null-terminated string which is to be
  667.             examined.
  668.     topattern - pointer to a buffer which contains at least as many
  669.             bytes as the string pattern. Can be set to 0 if you
  670.             don't want the string to be copied.
  671.     flags     - has to be NULL for now.
  672.  
  673.    RESULT
  674.     result   - 0 if the pattern contains no pattern characters. So
  675.            you can use strcmp (topattern, teststring) to test for a
  676.            match.
  677.            Otherwise it's a real pattern and you have to call
  678.            AllocPattern/NoCase(). Note: Call
  679.            AllocPattern/NoCase() with the original pattern!
  680.  
  681.    BUGS
  682.     No known bugs
  683.  
  684.    SEE ALSO
  685.     AllocPattern(), MatchThePattern()
  686.  
  687.  
  688. pattern.library/MatchThePattern                 pattern.library/MatchThePattern
  689.  
  690.    NAME
  691.     MatchThePattern -- Matches a pattern with a string
  692.  
  693.    SYNOPSIS
  694.     result = MatchThePattern (ph, string)
  695.     D0                        D0  A0
  696.  
  697.     LONG MatchThePattern (LONG, STRPTR)
  698.  
  699.    FUNCTION
  700.     This function tests if a pattern matches with the given string
  701.     or not. This function is case-sensitive.
  702.     NOTE: Make sure you don't call this function more than once AT THE
  703.           SAME TIME with the same pattern-handle ph (e.g. using
  704.           it in another task or process). Parts of the patternhandle
  705.           will be changed while matching.
  706.  
  707.    INPUTS
  708.     ph     - PatternHandle. You get this calling AllocPattern()
  709.     string - pointer to a null-terminated string which has to be
  710.          tested for a match.
  711.  
  712.    RESULT
  713.     result - 1L if the string matches with the pattern.
  714.          0L if the string doesn't match.
  715.          Any other negative value signals a fatal error.
  716.  
  717.    BUGS
  718.     No known bugs
  719.  
  720.    SEE ALSO
  721.     AllocPattern()
  722.  
  723.  
  724. pattern.library/PatternError2DOS               pattern.library/PatternError2DOS
  725.  
  726.    NAME
  727.     PatternError2DOS -- converts error-number
  728.  
  729.    SYNOPSIS
  730.     doserror = PatternError2DOS (patternerror)
  731.     D0                           D0
  732.  
  733.     LONG PatternError2DOS (LONG)
  734.  
  735.    FUNCTION
  736.     This functions converts an errornumber returned by AllocPattern(),
  737.     AllocPatternNoCase(), MatchThePattern(),... to an existing
  738.     AmigaDOS 2.0 errornumber.
  739.  
  740.    INPUTS
  741.     patternerror - the negative, private errorcode returned by
  742.                AllocPattern(), AllocPatternNoCase(),
  743.                MatchThePattern(), SimpleMatch() or
  744.                SimpleMatchNoCase ()
  745.  
  746.    RESULT
  747.     doserror - the non-private dos-errorcode.
  748.  
  749.    BUGS
  750.     No known bugs
  751.  
  752.    SEE ALSO
  753.     PatternErrorString()
  754.  
  755.  
  756. pattern.library/PatternErrorString           pattern.library/PatternErrorString
  757.  
  758.    NAME
  759.     PatternErrorString -- converts an errornumber to an errorstring
  760.  
  761.    SYNOPSIS
  762.     errorstring = PatternErrorString (patternerr, language, buf, buflen)
  763.     D0                                D0          A0        A1   D1
  764.  
  765.     STRPTR PatternErrorString (LONG, STRPTR, STRPTR, ULONG)
  766.  
  767.    FUNCTION
  768.     This function returns a pointer to an error-description. There are
  769.     a lot of translations into different languages. Refer to the file
  770.     "Config-Pattern".
  771.     NOTE: This must be only called by a process!!!
  772.  
  773.    INPUTS
  774.     patternerr - the negative, private errorcode returned by
  775.              AllocPattern(), AllocPatternNoCase(),
  776.              MatchThePattern(), SimpleMatch() or
  777.              SimpleMatchNoCase ()
  778.     language   - Describes which language you want to get back.
  779.              If the demanded language is not available, the english
  780.              errorstring will be returned.
  781.     buf    - specifies a buffer to receive the error message
  782.     buflen - specifies the length of the buffer, should be at least
  783.          50 in this version.
  784.  
  785.    RESULT
  786.     errorstring - a pointer to the text that describes the error.
  787.  
  788.    BUGS
  789.     No known bugs
  790.  
  791.    SEE ALSO
  792.     PatternError2DOS()
  793.  
  794.  
  795. pattern.library/SimpleMatch                         pattern.library/SimpleMatch
  796.  
  797.    NAME
  798.     SimpleMatch -- Matches a pattern with one string
  799.  
  800.    SYNOPSIS
  801.     result = SimpleMatch (pattern, string)
  802.     D0                    A0       A1
  803.  
  804.     LONG SimpleMatch (STRPTR, STRPTR)
  805.  
  806.    FUNCTION
  807.     This function matches one pattern with one string in a case-sensitive
  808.     way. You should only use this function, if you don't want to match
  809.     the pattern with more than one string, otherwise you will be very
  810.     slow!
  811.  
  812.    INPUTS
  813.     pattern - pointer to a null-terminated string which contains the
  814.           pattern.
  815.     string  - pointer to a null-terminated string which has to be
  816.           tested for a match.
  817.  
  818.    RESULT
  819.     result - 1L if the string matches with the pattern.
  820.          0L if the string doesn't match.
  821.          Any other negative value signals a fatal error.
  822.  
  823.    BUGS
  824.     No known bugs
  825.  
  826.    SEE ALSO
  827.     SimpleMatchNoCase(), AllocPattern(), MatchThePattern(), FreePattern()
  828.  
  829.  
  830. pattern.library/SimpleMatchNoCase             pattern.library/SimpleMatchNoCase
  831.  
  832.    NAME
  833.     SimpleMatchNoCase -- Matches a pattern with one string,
  834.                  case-insensitive
  835.  
  836.    SYNOPSIS
  837.     result = SimpleMatchNoCase (pattern, string)
  838.     D0                          A0       A1
  839.  
  840.     LONG SimpleMatchNoCase (STRPTR, STRPTR)
  841.  
  842.    FUNCTION
  843.     This function matches one pattern with one string in a
  844.     case-insensitive way. You should only use this function, if you
  845.     don't want to match the pattern with more than one string,
  846.     otherwise you will be very slow!
  847.  
  848.    INPUTS
  849.     pattern - pointer to a null-terminated string which contains the
  850.           pattern.
  851.     string  - pointer to a null-terminated string which has to be
  852.           tested for a match.
  853.  
  854.    RESULT
  855.     result - 1L if the string matches with the pattern.
  856.          0L if the string doesn't match.
  857.          Any other negative value signals a fatal error.
  858.  
  859.    BUGS
  860.     No known bugs
  861.  
  862.    SEE ALSO
  863.     SimpleMatch(), AllocPatternNoCase(), MatchThePattern(),
  864.     FreePattern()
  865.  
  866.  
  867. pattern.library/Str2Lower                             pattern.library/Str2Lower
  868.  
  869.    NAME
  870.     Str2Lower -- Converts a string to lowercase, including umlauts
  871.  
  872.    SYNOPSIS
  873.     lowerstring = Str2Lower (anystring)
  874.     D0                       A0
  875.  
  876.     STRPTR Str2Lower (STRPTR)
  877.  
  878.    FUNCTION
  879.     This function converts a given string - including umlauts - to
  880.     lowercase. If any character is a non-alphabetical character,
  881.     nothing will change. The result overwrites the input.
  882.  
  883.    INPUTS
  884.     anystring - the null-terminated string that is to be converted. This
  885.             will be overwritten!
  886.  
  887.    RESULT
  888.     lowerstring - pointer to the converted string.
  889.  
  890.    BUGS
  891.     No known bugs
  892.  
  893.    SEE ALSO
  894.     Char2Lower(), Char2Upper(), Str2Upper()
  895.  
  896.  
  897. pattern.library/Str2Upper                             pattern.library/Str2Upper
  898.  
  899.    NAME
  900.     Str2Upper -- Converts a string to uppercase, including umlauts
  901.  
  902.    SYNOPSIS
  903.     upperstring = Str2Upper (anystring)
  904.     D0                       A0
  905.  
  906.     STRPTR Str2Upper (STRPTR)
  907.  
  908.    FUNCTION
  909.     This function converts a given string - including umlauts - to
  910.     uppercase. If any character is a non-alphabetical character,
  911.     nothing will change. The result overwrites the input.
  912.  
  913.    INPUTS
  914.     anystring - the null-terminated string that is to be converted. This
  915.             will be overwritten!
  916.  
  917.    RESULT
  918.     upperstring - pointer to the converted string.
  919.  
  920.    BUGS
  921.     No known bugs
  922.  
  923.    SEE ALSO
  924.     Char2Lower(), Char2Upper(), Str2Lower()
  925.  
  926.  
  927. pattern.library/XMatchPattern                     pattern.library/XMatchPattern
  928.  
  929.    NAME
  930.     XMatchPattern -- Checks for a pattern match with a string
  931.  
  932.    SYNOPSIS
  933.     match = XMatchPattern (pat, str)
  934.     D0                     D1   D2
  935.  
  936.     BOOL XMatchPattern (STRPTR, STRPTR)
  937.  
  938.    FUNCTION
  939.     Checks for a pattern match with a string.  The pattern must be
  940.     the output by XParsePattern(). This routine is case-sensitive.
  941.     NOTES: Make sure you've a lot of free stack. There's _no_
  942.     built-in-stack-checking in this routine!
  943.     This function call is compatible to AmigaDOS 2.0. Please note
  944.     that you'd be better off using MatchThePattern() if you don't
  945.     _need_ to be compatible with AmigaDOS 2.0 !!!
  946.     NOTE: This must be only called by a process!!!
  947.  
  948.    INPUTS
  949.     pat - Special pattern string to match as returned by XParsePattern()
  950.     str - String to match with given pattern
  951.  
  952.    RESULT
  953.     match - success or failure of pattern match.  On failure,
  954.         IoErr() will return 0 or an error.
  955.  
  956.    SEE ALSO
  957.     XParsePattern(), XMatchPatternNoCase()
  958.     dos.library/MatchPattern()
  959.  
  960.  
  961. pattern.library/XMatchPatternNoCase         pattern.library/XMatchPatternNoCase
  962.  
  963.    NAME
  964.     XMatchPatternNoCase -- Checks for a pattern match with a string
  965.  
  966.    SYNOPSIS
  967.     match = XMatchPatternNoCase (pat, str)
  968.     D0                           D1   D2
  969.  
  970.     BOOL XMatchPatternNoCase (STRPTR, STRPTR)
  971.  
  972.    FUNCTION
  973.     Checks for a pattern match with a string.  The pattern must be
  974.     the output by XParsePatternNoCase(). This routine is
  975.     case-insensitive.
  976.  
  977.     NOTES: Make sure you've a lot of free stack. There's _no_
  978.     built-in-stack-checking in this routine!
  979.     This function call is compatible to AmigaDOS 2.0. Please note
  980.     that you'd be better off using MatchThePattern() if you don't _need_
  981.     to be compatible with AmigaDOS 2.0 !!!
  982.     NOTE: This must be only called by a process!!!
  983.  
  984.    INPUTS
  985.     pat - Special pattern string to match as returned by
  986.           XParsePatternNoCase()
  987.     str - String to match with given pattern
  988.  
  989.    RESULT
  990.     match - success or failure of pattern match.  On failure,
  991.         IoErr() will return 0 or an error.
  992.  
  993.    SEE ALSO
  994.     XParsePattern(), XMatchPattern()
  995.     dos.library/MatchPatternNoCase()
  996.  
  997.  
  998. pattern.library/XParsePattern                     pattern.library/XParsePattern
  999.  
  1000.    NAME
  1001.     XParsePattern -- Create a tokenized string for XMatchPattern()
  1002.  
  1003.    SYNOPSIS
  1004.     IsWild = XParsePattern (Source, Dest, DestLength)
  1005.     D0                      D1      D2    D3
  1006.  
  1007.     LONG XParsePattern (STRPTR, STRPTR, LONG)
  1008.  
  1009.    FUNCTION
  1010.     Creates the output needed by XMatchPattern(). Also indicates if
  1011.     there are any wildcards in the pattern.
  1012.     NOTE: This function call is compatible with AmigaDOS 2.0, but
  1013.     if there is any possibility to use AllocPattern(), you'd be better
  1014.     off to use that function!
  1015.     NOTES: This must be only called by a process!!!
  1016.            The compiled pattern is NOT compatible to a pattern, that
  1017.            was compiled using AmigaDOS 2.0 ParsePattern(). So don't
  1018.            use this output in AmigaDOS 2.0 MatchPattern() and
  1019.            vice versa.
  1020.  
  1021.    INPUTS
  1022.     Source     - unparsed wildcard string to search for.
  1023.     Dest       - output string for use with XMatchPattern()
  1024.     DestLength - length available in destination
  1025.  
  1026.    RESULT
  1027.     IsWild - 1 means there were wildcards in the pattern,
  1028.          0 means there were no wildcards in the pattern,
  1029.         -1 means there was a buffer overflow or other error
  1030.  
  1031.    SEE ALSO
  1032.     XParsePatternNoCase(), XMatchPattern()
  1033.     dos.library/ParsePattern()
  1034.  
  1035.  
  1036. pattern.library/XParsePatternNoCase         pattern.library/XParsePatternNoCase
  1037.  
  1038.    NAME
  1039.     XParsePatternNoCase -- Create a tokenized string for
  1040.                    XMatchPatternNoCase()
  1041.  
  1042.    SYNOPSIS
  1043.     IsWild = XParsePatternNoCase (Source, Dest, DestLength)
  1044.     D0                            D1      D2    D3
  1045.  
  1046.     LONG XParsePatternNoCase (STRPTR, STRPTR, LONG)
  1047.  
  1048.    FUNCTION
  1049.     Creates the output needes by XMatchPatternNoCase(). Also indicates
  1050.     if there are any wildcards in the pattern.
  1051.     NOTE: This function call is compatible to AmigaDOS 2.0. But
  1052.     if there is any possibility to use AllocPattern(), you'd
  1053.     be better off to use this function!
  1054.     NOTES: This must be only called by a process!!!
  1055.            The compiled pattern is NOT compatible to a pattern, that
  1056.            was compiled using AmigaDOS 2.0 ParsePattern(). So don't
  1057.            use this output in AmigaDOS 2.0 MatchPattern() and
  1058.            vice versa.
  1059.  
  1060.    INPUTS
  1061.     Source     - unparsed wildcard string to search for.
  1062.     Dest       - output string for use with XMatchPatternNoCase()
  1063.     DestLength - length available in destination
  1064.  
  1065.    RESULT
  1066.     IsWild - 1 means there were wildcards in the pattern,
  1067.          0 means there were no wildcards in the pattern,
  1068.         -1 means there was a buffer overflow or other error
  1069.  
  1070.    SEE ALSO
  1071.     XParsePattern(), XMatchPatternNoCase()
  1072.     dos.library/ParsePatternNoCase()
  1073.  
  1074.